AmigActive 10

home *** CD-ROM | disk | FTP | other *** search

/ AmigActive 10 / AACD 10.iso / AACD / Programming / mpatrol / FAQ < prev next >

Wrap

Text File | 2000-05-16 | 20.7 KB | 376 lines

FAQ FOR THE MPATROL LIBRARY This file contains frequently asked questions about the mpatrol library and their corresponding answers or solutions. 1. DOCUMENTATION Q. I can't seem to format the TeXinfo manual for mpatrol into anything that I can view or print. What am I doing wrong? A. You'll need to have the appropriate document formatting programs installed on your system before you can do this, and even then you'll also need to have suitable software for viewing or printing the formatted documents. You can download an archive containing the latest mpatrol manual in a variety of formats from http://www.cbmamiga.demon.co.uk/mpatrol/ and this will also contain a file telling you where to get programs that can be used to view or print these files. Alternatively, you can browse the latest mpatrol manual on-line at the same site. Q. I'd like to convert the mpatrol manual to a different documentation format but there is no support for that format in the Makefile. How would I go about doing this? A. Since TeXinfo is intended to be converted to other documentation formats it should be fairly easy for you to find a tool which will convert it into your desired format. I plan to also provide the mpatrol manual in DocBook format if and when a suitable TeXinfo to DocBook converter becomes available, but I won't provide preformatted versions of the mpatrol manual in any other format which isn't already supported. Q. Why is the reference card not centred in the middle of the page when I print it? A. The reference card has three columns in landscape format and as a result requires smaller margins than LaTeX normally uses. When dvips converts the DVI file to a postscript file it refers to a configuration file set up for a specific printer so that it knows what that printer's capabilities are. However, you can instruct dvips to offset the page by a given amount with the -O option so that it appears centred when printed. I find that -O -0.75in,0.25in works for me. Note that the default paper size for the reference card is DIN A4, but you can change it to US letter in the LaTeX source file. Q. How do I install the mpatrol manual as a GNU info file? A. Assuming you have the GNU info file built and copied to your system's info file directory, you should use the install-info command to place an entry for mpatrol in your system's GNU info directory file, otherwise the GNU info reader may not be able to locate the mpatrol entry. You may also need to modify your INFOPATH environment variable if you installed the GNU info file in a non-standard place. Q. How do I install the mpatrol manual pages? A. This is very system-dependent, but need only be done on UNIX systems since they cannot be used on other platforms. The unformatted manual pages exist in man/man1 and man/man3 and should be copied to your system's manual page directory. If you don't have the nroff command installed on your system then you may also need to copy the formatted manual pages, located in man/cat1 and man/cat3. You may also need to modify your MANPATH environment variable if you installed the manual pages in a non-standard place, and some systems require you to update the whatis database after installing new manual pages, by running makewhatis, catman or equivalent. Note that there are two manual pages for mpatrol with the same name and you are likely to see the section 1 manual page by default. You must explicitly specify the section number when using the man command in order to view the other manual page. 2. BUILDING Q. Why does the makefile assume that I am building mpatrol on platform X when I am really building on platform Y? A. The src/config.h and src/target.h header files attempt to obtain as much information from the compiler as possible, mainly from any predefined preprocessor macros that it defines during compilation. If this information is incorrect then you can override the TARGET, SYSTEM, ARCH and FORMAT preprocessor macros defined in src/target.h to suit your particular system by explicitly defining them in CFLAGS within the makefile when you build mpatrol. You could also choose to build different versions of mpatrol with different settings of FORMAT on a single system if you wish to by changing FORMAT for different builds. Q. I cannot include mpatrol.h from my C++ source code as I get lots of compilation errors. Why is this and what can I do to prevent them? A. The most likely reason that you are getting errors is because you are calling placement new, and the way that mpatrol derives source information from calls to operator new is by defining a macro called new, thus causing lots of problems when calling placement new or explicitly calling operator new. You can either try not to use placement new or you can define the preprocessor macro MP_NOCPLUSPLUS when compiling your source file, which will disable the overriding of any C++ operators in mpatrol.h. Q. I still have the above problem, but I don't think it's due to placement new since the compiler complains about operator new[], so could that be a clue? A. Yes. The most likely reason is that the C++ compiler does not support the array new and delete operators. These were introduced some time before the standardisation of the C++ language but some compilers may not yet have support for them. It may be that you have to use a special compiler option to enable support for these operators, but if not you will probably have to edit mpatrol.h to temporarily allow your files to compile. Q. Why do some of the makefiles contain the -fno-inline-functions option as part of OFLAGS? A. The -fno-inline-functions option is a GCC-specific option which instructs the compiler not to inline any functions. This is necessary on some platforms where function call stack traversal is supported, since function inlining may significantly alter the layout of a program's stack. Normally this option is only required when building the mpatrol library, but on some platforms function call stack traversal may not work properly unless this option (or equivalent) is used for all compiled code. 3. LINKING Q. Why do I get undefined symbols when linking with the mpatrol library? A. This is most likely caused by the mpatrol library requiring additional symbols defined in an object file access library. If mpatrol was built with FORMAT=FORMAT_ELF32 then you'll need to add -lelf (or equivalent) to the compiler command line straight after -lmpatrol. If mpatrol was built with FORMAT=FORMAT_BFD then you'll need to add -lbfd -liberty (or equivalent) instead. If you are using the thread-safe version of mpatrol then you may also need to link with the system threads library. Q. Why do I get duplicate definitions of symbols when linking with the mpatrol library? A. This is most likely caused by your code, or a library, providing definitions of malloc() and free() which conflict with those defined in the mpatrol library. You'll need to disable these in order to perform a successful link and use the replacements in mpatrol instead. Q. I linked my program to a shared library version of mpatrol. Now, when I try to run my program, the system complains that it cannot find the mpatrol library. How do I get this to work? A. You need to tell the system where to find the shared library version of the mpatrol library, either by setting your LD_LIBRARY_PATH environment variable (or just PATH on Windows platforms), or by embedding the full path to the library into the executable when you link your program by setting the LD_RUN_PATH environment variable. Q. I linked my program to a shared library version of mpatrol. Will future releases of mpatrol remain compatible with this version or will I have to relink my program? A. Backwards compatibility is not generally guaranteed, but should be preserved if only the bug fix part of the mpatrol version number has changed, with the major and minor versions staying the same. For example, versions 1.0.3 and 1.0.8 should be compatible, but upgrading to version 1.1.0 may require a relink. Q. I have linked my program with the DLL version of the mpatrol library on Windows but it crashes when I run it. I suspect that the crash is occurring when the mpatrol library is being initialised, so what is going wrong? A. There appears to be a problem when using the mpatrol DLL and the static version of the Microsoft C run-time library, and also a problem when using the static version of mpatrol and the Microsoft C run-time library DLL. Luckily, if you ensure that you use either both static libraries or both DLLs at the same time then the problem should go away. There doesn't seem to be an easier way around it at this time or, for that matter, an explanation for why it happens 4. RUNNING Q. I've just linked and run my program with the mpatrol library, but the resulting log file doesn't contain any useful information. Why does it not contain a list of all memory transactions or show any unfreed memory allocations? A. By default, the mpatrol library will only write a summary of library settings and statistics to the log file, and that will only occur on successful program termination (i.e. when exit() is called). If this does not appear then it is likely that your program (or some other library function) called abort() due to a fatal error. However, there are a multitude of different options that you can pass to the mpatrol library via the MPATROL_OPTIONS environment variable that will allow you to control what is logged and what is not. Note that the mpatrol command will always log all calls to allocate, reallocate and free memory by default. Q. I linked my program with the mpatrol library to trace all of its memory operations, such as memcpy() and memcmp(), but I get nothing in the log file. Why is this? A. The memory operation functions do not automatically initialise the mpatrol library since on many systems the startup routines call them very early on. If your program does not call any memory allocation functions to initialise the mpatrol library then you must explicitly call the __mp_init() function. All memory operation functions following that call with then be traced. Q. Why does the USEDEBUG option not work for me? A. Firstly, you have to ensure that you have built the mpatrol library with support for the GNU BFD object file access library by compiling with the FORMAT=FORMAT_BFD preprocessor macro definition. Secondly, you have to ensure that you have compiled all relevant object files with debugging information enabled (usually by adding an option to the compiler command line), although the mpatrol library does not need to be compiled this way. The file and line number information will hopefully then appear in the log file for all symbols that have associated debugging information. Q. Why do some mpatrol log file entries only contain a partial call stack rather than following the function call stack back to the call to main()? A. This could be because the mpatrol library was compiled with limited call stack traversal support via the MP_BUILTINSTACK_SUPPORT configuration macro. However, it could also mean that the mpatrol library encountered a corrupt frame pointer when traversing the call stack and had to terminate the recursion. The frame pointer MUST be preserved from function to function on most platforms, otherwise the stack cannot be traversed. See your compiler manual for further details. Q. I am trying to use the mpatrol command to debug an executable file that was not originally compiled with the mpatrol library. However, even though it runs successfully, no mpatrol log file is produced. Why is this? A. First, check that you are passing the -d option to the mpatrol command. If that doesn't work then check that the executable file has been dynamically linked; statically linked executables cannot be forced to use the mpatrol library. If it still doesn't work then it may be that the dynamic linker on your system doesn't have the ability to preload any shared libraries that have been specified in a special environment variable, in which case you can't use this feature. Q. I know that there's a definite heap corruption problem in my program as it keeps crashing in unrelated code due to pointer corruption, and when I link with the mpatrol library it stops crashing. What can I do? A. Try as many of the relevant mpatrol run-time options as possible and make sure that you closely examine the mpatrol log file for warnings and errors - your problem may have been noticed by the mpatrol library but it may not have considered it a fatal error and continued execution. If this still doesn't show up anything then you can probably rest assured that you have a memory corruption problem but you may need to use a commercial product such as Purify to isolate it. If that fails then you'll just have to employ the traditional debugging method of single-stepping through your program in a debugger until something unusual or unexpected happens. Q. If I link my program to version 1.0 of the mpatrol library then I cannot interrupt it using the keyboard, which I would normally be able to do without using mpatrol. Is this a bug? A. Not really, but it is undesirable behaviour in most cases, which is why it was removed in later releases of mpatrol and replaced with the SAFESIGNALS option. The reason that the program could not be interrupted using the keyboard was that mpatrol would ignore such signals when its library code was being executed, otherwise user-defined signal handlers that used malloc() and related functions would have the capability to cause lots of undesirable side effects. However, this does not normally happen, which is why the behaviour was moved to an option for those that needed it. Q. I've linked and run my program with mpatrol under UNIX and it uses a large amount of heap memory. However, it crashes near the end of execution and then proceeds to freeze up the whole system, sometimes requiring a reboot. What am I doing wrong? A. The most common possible explanation for this is that you are running your program with too much access to system resources. What is likely to be happening is that when your program crashes the system attempts to dump the entire process image to a core file for later debugging in a non-symbolic debugger. If the process has a huge heap then the core file is also going to be huge, thus resulting in a massive file that may lead to the system thrashing while it attempts to write it to the disk. Technically, the system has not frozen, but it is likely to take a long time to finish writing the file. The best solution involves setting your program's maximum core file size to a reasonable limit (or just zero), and also possibly limiting your program's maximum data segment size as well. These can be set from the shell but the exact details on how to do this differ between shells. Q. Why does my program run so slowly after I link it with the mpatrol library? A. Normal malloc libraries are optimised for speed but will typically fall over at the slightest hint of an error. Debugging malloc libraries are written to provide as much debugging information as possible whilst performing a multitude of additional checks, which is why they may run much slower. However, you can control which checks are performed (and when) by using the MPATROL_OPTIONS environment variable. Performance may also be lost if you make lots of small memory allocations rather than fewer larger allocations, but that is mainly due to the overhead of storing the extra tracing details for each memory allocation. Q. My program is written in C++ and is linked to the mpatrol library, but how do I go about demangling the C++ symbol names that are shown in the stack tracebacks in the resulting log file? A. Because there is no standard way of mangling C++ symbol names, various compilers and operating systems have taken different approaches to C++ name mangling, many of which differ significantly from the method suggested in The Annotated C++ Reference Manual by Margaret Ellis and Bjarne Stroustrup. However, most compilers come with a demangling tool which can be used in a command pipe to accept mangled names on its standard input file stream and demangle them on its standard output file stream, and so can be used to process the mpatrol log file. Q. Why does my program not stop when the mpatrol library notices an error? A. The library was written to give as much information as possible and so sometimes, when a non-fatal error is discovered, the library will write the error message to the log file and continue in the hope of being able to uncover more errors during the execution of the program. This means that you should always check the number of warnings and errors given in the summary at the end of program execution, and then search backwards in the log file for WARNING or ERROR. Q. I have linked my program with the mpatrol library on an Amiga or Netware machine, but when it runs it still crashes the entire system. Why is this? A. AmigaOS and Netware do not have virtual memory and so do not have memory protection turned on by default. This means that any rogue write to an erroneous address may actually overwrite the data of another process or perhaps even the operating system, thus bringing the entire machine down. There are several third-party system utilities available for the Amiga to add memory protection to machines with built-in MMUs, which can then be used in conjunction with mpatrol. I'm not sure about the availability of such software for Netware. Q. I have built the mpatrol library with GCC on AmigaOS and have successfully linked it to my program. However, why are none of the options in the MPATROL_OPTIONS environment variable recognised when I run it? A. The getenv() function in the GNU C library is not compatible with the AmigaDOS SetEnv and GetEnv commands since it does not treat environment variables as files located in ENV: and is only compatible with software that uses the ixemul library. However, the env command that comes with most GNU software distributions allows you to set an environment variable that the GNU getenv() function can read when you are running in AmigaDOS. Q. How do I suppress all diagnostic output from the mpatrol library? A. You can do this by setting the mpatrol log file to be your system's "bit bucket", which is /dev/null on UNIX platforms and NIL: on AmigaOS. There doesn't appear to be an equivalent way to do this on Windows or Netware. 5. FILES Q. Why is there a libmpatrol.o target in the UNIX and Amiga Makefiles? A. This is simply used to build the mpatrol library as one large object file for full incorporation into other libraries and was used during the development of mpatrol. On UNIX platforms some linkers support the -r option for combining many object files into one large object file, but this is not universally supported, hence the reason for using the compiler instead. Because all of the source files are compiled at once, there may be conflicts with system header files when malloc() and its related functions are being compiled, which is why such an object file is not built by default. Note that the Windows and Netware Makefiles use libmpatrol.obj. Q. What are the CVS subdirectories that come with the mpatrol distribution? A. CVS stands for Concurrent Versions System and is a project version control system. All of the source files that comprise an mpatrol release are stored in a central CVS repository so that previous releases can be easily retrieved, but the CVS system needs to have a way of determining the versions of currently checked-out files, hence the CVS subdirectories. You shouldn't need to worry about them, so just ignore them. Q. What does the mupdate shell script do? A. This is for my use in order to automate every new release of mpatrol. You should never need to run this script and it should not be installed anywhere on your system. This script also uses and modifies the VERSION file and updates the NEWS and ChangeLog files.